package com.xyzwps.collections;

/**
 * 线性表抽象。
 * <p>
 * 对于线性表的任何涉及索引的操作，有效的索引范围始终是 [0, n)。
 * 如果索引值超出此范围，则抛出 {@link IndexOutOfBoundsException}。
 *
 * @param <E> 线性表中元素的类型
 */
public interface List<E> extends Collection<E>, Iterable<E>, Indexed<Integer, E> {

    // TODO: 类 lodash 操作
    // TODO: sublist
    // TODO: foreach
    // TODO: removeAll
    // TODO: addAll(Collection<E> elements)

    /**
     * 添加一组元素到列表末尾。
     */
    void addAll(E[] elements);

    /**
     * 在把指定索引处及其之后的元素往后推一格，并把此索引处的元素指定为新元素。
     *
     * @throws IndexOutOfBoundsException 当索引不在区间 [0, n) 中时。
     */
    void insertAt(int index, E element);

    /**
     * 移除指定索引处的元素，并返回被移除的元素。
     *
     * @throws IndexOutOfBoundsException 当索引不在区间 [0, n) 中时。
     */
    E removeAt(int index);

    /**
     * 从索引 0 处开始往后数，移除第一个匹配的元素。如果元素存在，则返回被移除元素所在的索引，否则返回 -1。
     */
    int removeFirst(E element);

    /**
     * 从索引 0 处开始往后数，返回元素第一次出现的位置的索引。如果元素不存在，则返回 -1。
     */
    int indexOf(E element);
}
